Skip to content
← 回到文章列表

Claude Code 命令与技巧全览 ​

这篇是我自己学 Claude Code 时整理的速查手册。所有内容都对照了 官方文档 和本机 claude --help 的输出,写作时的版本是 v2.1.310(2026 年 10 月)。

  • Claude Code 更新很快,几乎每周都有命令增删,所以以你本机为准:在会话里敲 / 能看到当前可用的全部命令,claude --help 列出全部启动参数,/release-notes 看更新日志。
  • 下文表格里标 ★ 的是日常最常用的命令和快捷键,初学先记这些就够了。
  • 不是每个命令每个人都有。可用与否取决于平台、套餐和登录方式,比如 /desktop 只在 macOS 和 x64 Windows 且用 Claude 订阅登录时出现,/upgrade 在 Enterprise 套餐下不显示。

启动:命令行参数 ​

最常用的几种启动方式 ​

命令作用
claude ★在当前目录启动交互式会话
claude "解释一下这个项目"启动交互式会话,并把这句话作为第一条消息
claude -p "查询" ★非交互模式:输出结果后直接退出,适合脚本和管道
cat log.txt | claude -p "解释这个报错"把管道内容喂给 Claude
claude -c ★继续当前目录下最近一次对话
claude -r ★打开会话选择器;claude -r auth-refactor 按名字或 ID 恢复
claude -n 名字给本次会话起名,显示在输入框、/resume 列表和终端标题里
claude -w feature-auth ★在 .claude/worktrees/feature-auth 新建一个 git worktree 并在里面启动
claude --bg "任务"在后台启动会话并立即返回,打印的 ID 给 claude attach / logs / stop 用

常用参数 ​

参数作用
--model <model> ★指定模型,可以写别名(fable、opus、sonnet)或完整模型名
--effort <level>推理强度:low、medium、high、xhigh、max
--permission-mode <mode> ★启动时的权限模式:acceptEdits、auto、bypassPermissions、manual、dontAsk、plan
--add-dir <dirs...>额外允许访问的目录
--allowedTools / --disallowedTools放行 / 禁止某些工具,如 "Bash(git *) Edit"
--tools <tools...>限定可用的内置工具集合,"" 表示全部禁用
--agent <agent>让整个会话以某个子代理的身份运行
--append-system-prompt <prompt>在默认系统提示后追加内容;--system-prompt 则是整体替换
--mcp-config <configs...>从 JSON 文件或字符串加载 MCP 服务器;配合 --strict-mcp-config 只用这些
--settings <file-or-json>本次会话额外加载一份设置
--fork-session配合 -r / -c,恢复时生成新的会话 ID,原会话不动
--from-pr [value]恢复与某个 PR 关联的会话
--chrome / --ide启用 Claude in Chrome / 启动时自动连接 IDE
-d, --debug [filter]调试模式,可按类别过滤,如 --debug=hooks,mcp
--safe-mode关掉所有自定义(CLAUDE.md、skills、插件、hooks、MCP 等)启动,排查配置问题用
--bare极简模式:跳过 hooks、插件、自动记忆、CLAUDE.md 自动发现等,脚本里启动更快
--dangerously-skip-permissions跳过所有权限检查。官方建议只在没有外网的沙箱里用

只对 -p 生效的参数:--output-format(text / json / stream-json)、--input-format、--json-schema(结构化输出)、--max-budget-usd(花费上限)、--no-session-persistence、--include-partial-messages。

子命令 ​

子命令作用
claude update ★检查并安装更新(别名 upgrade)
claude install [target]安装原生版本,可指定 stable、latest 或具体版本号
claude doctor检查安装健康状况;会话里的 /doctor 更全,还能帮你修
claude mcp ★管理 MCP 服务器,见下文
claude plugin管理插件
claude auth管理登录认证
claude setup-token生成长期有效的认证 token(需要 Claude 订阅)
claude agents列出和管理后台会话
claude attach <id>把一个后台会话接回当前终端
claude logs <id>打印后台会话最近的输出
claude stop <id>停止后台会话,对话保留
claude rm <id>删除后台会话(安全时连 worktree 一起删)
claude ultrareview [target]在云端跑多代理代码评审
claude import [source]从别的 AI 编码工具导入配置
claude purge [path]删除某个项目的全部 Claude Code 状态(对话记录、文件历史等)

子命令拼错时,Claude Code 会提示最接近的那个并退出,比如 claude udpate 会打印 Did you mean claude update?。

输入框:前缀与多行 ​

开头字符决定输入的含义 ​

输入含义
/ 开头 ★命令或 skill。只有出现在消息开头才会执行,后面的文字是它的参数
! 开头 ★Shell 模式:直接跑命令,不经过 Claude 审批,命令和输出进入上下文,Claude 会接着解读
@ ★引用文件路径(带自动补全),也可以 @ 目录、@server:resource 引用 MCP 资源
:输入 :name: 插入 emoji
空输入框里按 ?打开快捷键帮助面板

几个细节:

  • ! npm test 跑完后 Claude 会自动解释输出,消耗等同发一条普通消息。只想把输出放进上下文、不要回复,可在 settings.json 里把 respondToBashCommands 设为 false。
  • Shell 模式下用 Tab 可以从当前项目以前的 ! 命令里补全;输入带 / 的路径会弹出文件补全。退出 Shell 模式:空输入时按 Esc、Backspace 或 Ctrl+U。
  • @src/utils/auth.js 会把文件内容直接放进对话(在 Read 工具的 token 上限内,默认 25,000 token;超过 256KB 的文本文件不会放进去)。
  • 一条消息可以叠多个 skill:/write-tests /fix-issue 123 会加载两个 skill,123 作为参数传给每一个,最多叠六个。
  • 在句子中间敲 / 也有补全(比如 跑完测试再 /com),但只有开头的命令会被执行。

多行输入 ​

方式说明
\ + Enter ★所有终端都能用
Ctrl+J所有终端都能用,不需要配置
Shift+Enter ★iTerm2、WezTerm、Ghostty、Kitty、Warp、Apple Terminal、Windows Terminal 原生支持;VS Code、Cursor 等可用 /terminal-setup 装上
Option+EntermacOS 上把 Option 设成 Meta 键之后可用
直接粘贴适合代码块和日志

图片 ​

三种方式:把图片拖进窗口;复制后用 Ctrl+V 粘贴(iTerm2 里是 Cmd+V,Windows/WSL 是 Alt+V);或者直接在消息里写图片路径。粘贴后会出现一个 [Image #N] 标记。

快捷键 ​

macOS 用户注意:Alt+B、Alt+F、Alt+D、Alt+Y、Alt+P 这类快捷键需要在终端里把 Option 设为 Meta 键。

常规控制 ​

快捷键作用
Esc ★打断 Claude 当前的回复或工具调用,已经做的工作保留;有对话框时关闭对话框
Esc Esc ★输入框有字时:清空并存进历史(按 Up 能找回);输入框为空时:打开回退(rewind)菜单
Ctrl+C ★有任务在跑时打断;没有时第一下清空输入,第二下退出
Ctrl+D退出(按两下,800ms 内);输入框有字时是向后删一个字符
Shift+Tab ★循环切换权限模式(Windows 某些情况下是 Alt+M)
Ctrl+B ★把正在运行的 Bash 命令或代理放到后台(tmux 里要按两次)
Ctrl+O ★打开 / 关闭对话详情视图,能看到每次工具调用的细节
Ctrl+T显示 / 隐藏 Claude 的任务清单
Ctrl+R ★反向搜索输入历史
Ctrl+G 或 Ctrl+X Ctrl+E ★用默认编辑器编辑当前输入(写长提示词很好用)
Ctrl+S暂存当前输入并清空;在空输入框再按一次恢复
Ctrl+L重绘屏幕,界面花了的时候用
Ctrl+V ★粘贴图片
Ctrl+Z挂起到 shell(仅 Unix),用 fg 回来
Ctrl+Enter 或 Ctrl+X Ctrl+S立即发送排队中的消息
Ctrl+X Ctrl+K停止本会话所有后台子代理(3 秒内按两次确认)
Option+P / Alt+P切换模型,不清空输入
Option+T / Alt+T开关扩展思考(对 Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 无效,它们始终开启)
Option+O / Alt+O开关 fast 模式
Up / Down在多行输入里移动光标,到首行 / 末行后再按就是翻历史
Tab接受补全建议

文本编辑 ​

快捷键作用
Ctrl+A / Ctrl+E移到行首 / 行尾
Ctrl+K删到行尾
Ctrl+U删到行首(macOS 终端里 Cmd+Backspace 映射到它)
Ctrl+W向前删到上一个空白,一下删掉一整个路径或 --flag=value
Ctrl+Y粘贴刚才删掉的文字;之后按 Alt+Y 循环更早的删除内容
Alt+B / Alt+F按词后退 / 前进
Alt+D删到词尾
Ctrl+_撤销上一次输入编辑

Vim 模式和自定义快捷键 ​

  • /vim 命令在 v2.1.92 已经移除,现在从 /config → Editor mode 切换。支持常见的 NORMAL / INSERT / VISUAL 操作:hjkl、w/b/e、dd、ciw、yy/p、u、. 等。NORMAL 模式下按 / 是历史搜索,不是命令菜单。
  • /keybindings 打开 ~/.claude/keybindings.json,可以改绑任意快捷键。

Claude 干活时也能继续打字 ​

Claude 在工作时按 Enter,消息会排队,不会打断当前这一轮。普通消息会在当前这批工具调用结束后、同一轮里就交给 Claude;命令和 ! 命令会等这一轮结束再按顺序执行。从输入框第一行按 Up 能把排队的内容收回来修改。

斜杠命令:全部清单 ​

这里收了当前文档里的全部内置命令。标 (skill) 的是内置 skill:本质是一段交给 Claude 的提示词,和你自己写的 skill 一样运作。参数里 <arg> 是必填,[arg] 是可选。

会话与上下文 ​

命令作用
/clear [name] ★开新对话、清空上下文(项目记忆保留)。别名 /reset、/new
/compact [instructions] ★把对话压缩成摘要以腾出上下文,可以附加摘要重点,如 /compact 重点保留 API 改动
/autocompact [auto|<tokens>]设置自动压缩的触发窗口,如 500k
/context [all] ★用彩色网格可视化上下文占用,并给出优化建议
/resume [session] ★恢复之前的对话,不带参数打开选择器。别名 /continue
/rename [name]重命名当前会话;不带参数则根据对话自动起名
/branch [name]从当前位置分出一个对话分支并切过去,原对话可用 /resume 回去
/fork [prompt]把当前对话复制成一个新的后台会话,你留在这里继续
/subtask <task>派一个继承完整对话的后台子代理去做事,结果会回到当前对话
/rewind ★回退代码和 / 或对话到某个检查点,或对某段对话做摘要。别名 /checkpoint、/undo
/btw [question] ★问个旁支问题,问答不进入对话历史;Claude 工作时也能问
/recap生成当前会话的一句话摘要
/export [filename]把对话导出为纯文本
/copy [N]复制最近一条回复(/copy 2 是倒数第二条),有代码块时可挑选;按 w 写入文件
/diff ★查看工作区改动,包括 Claude 到目前为止的编辑
/exit退出。别名 /quit

模型与推理 ​

命令作用
/model [model] ★切换模型并存为默认;选择器里按 s 只对本会话生效,左右方向键调推理强度
/effort [level|auto|status|ultracode [on|off]]设置推理强度;max 只对本会话有效
/fast [on|off]开关 fast 模式
/advisor [model|off]开关 advisor:关键时刻向第二个模型请教
/plan [description] ★进入计划模式,可直接带上任务,如 /plan 修复登录 bug
/goal [condition|clear]设一个目标,Claude 会跨多轮持续工作直到条件满足

权限与安全 ​

命令作用
/permissions ★管理 allow / ask / deny 规则和工作目录。别名 /allowed-tools
/sandbox开关沙箱模式(仅支持的平台)
/auto-mode-setup根据项目和最近的会话起草 auto 模式的环境描述,审阅后保存
/fewer-permission-prompts(skill) 扫描历史里常用的只读命令,生成 allowlist 写进项目 .claude/settings.json
/security-review检查当前分支相对 origin 默认分支的改动有没有安全漏洞(需要 origin remote)

项目配置与记忆 ​

命令作用
/init ★分析代码库,生成初始 CLAUDE.md;已有时给出改进建议。设 CLAUDE_CODE_NEW_INIT=1 走交互式流程,顺带配置 skills 和 hooks
/memory ★编辑 CLAUDE.md,开关 / 查看自动记忆
/config [key=value ...] ★打开设置面板,或直接 /config theme=dark、/config model=sonnet。别名 /settings
/add-dir <path>给本会话添加工作目录
/cd <path>把会话移到另一个目录,对话保留
/hooks查看 hook 配置
/statusline配置状态栏,描述你要什么或不带参数从 shell 提示符自动生成
/output-style [style]列出或切换输出风格
/theme切换配色主题,可新建自定义主题
/keybindings打开快捷键配置文件
/terminal-setup为当前终端装 Shift+Enter 换行等配置
/tui [default|fullscreen]切换渲染器,fullscreen 是无闪烁的全屏模式
/focus全屏模式下的精简视图:只看最后的提问、工具调用摘要和最终回复
/scroll-speed全屏模式下调整滚轮速度
/color [color|default]设置输入栏颜色
/update-config [request](skill) 用自然语言描述设置改动,Claude 去改对应的 settings.json
/import [codex|gemini|cursor]从 Codex、Gemini CLI、Cursor 导入配置

扩展:skills、插件、MCP、子代理 ​

命令作用
/skills ★列出可用 skill,按 t 按 token 数排序,空格 / 回车切换可见性
/reload-skills重新扫描 skill 目录,不用重启
/skill-doctor看每个 skill 占多少上下文、用了多少次
/plugin [subcommand]管理插件:list、install、enable、disable 等
/reload-plugins [--force]重新加载插件
/mcp ★管理 MCP 连接和 OAuth;/mcp reconnect all 重连所有失败的服务器
/agents现在只打印一句提示:让 Claude 帮你建子代理,或直接编辑 .claude/agents/(v2.1.197 及以前是交互界面)
/list-agents列出可以发消息的子代理和其他会话(需要开启跨会话消息)。别名 /peers
/plugin-authoring加载编写 mod 的参考资料
/workflow-authoring(skill) 加载编写动态 workflow 脚本的参考

代码评审与验证 ​

命令作用
/code-review [level] [--fix] [--comment] [target] ★(skill) 检查当前 diff 的正确性问题;--fix 直接修,--comment 发到 PR,ultra 走云端深度评审。可传 PR 号、分支或路径。别名 /review
/ultrareview [PR or branch]云端多代理深度评审,推荐写法是 /code-review ultra
/simplify [target](skill) 四个代理并行检查改动里可复用、可简化、可提效的地方并直接改,不找 bug
/verify(skill) 构建并实际运行应用来确认改动生效,不只看测试
/run(skill) 启动并操作你的应用,亲眼看到改动
/run-skill-generator(skill) 为项目生成一个教 /run、/verify 怎么启动应用的 skill
/autofix-pr [prompt]开一个云端会话盯住当前分支的 PR,CI 挂了或有评论时自动推修复

并行、后台与定时 ​

命令作用
/tasks ★查看和管理本会话的后台任务(包括已完成的子代理)。别名 /bashes
/background [prompt]把整个会话转到后台运行,释放终端。别名 /bg
/stop停止当前接入的后台会话
/batch <instruction>(skill) 大规模改动:拆成 5 到 30 个独立单元,每个在独立 worktree 里由后台子代理完成
/loop [interval] [prompt](skill) 会话开着期间定时重复执行,如 /loop 5m 看看部署完了没;不写间隔则由 Claude 自己掌握节奏
/schedule [description]创建 / 管理云端定时任务。别名 /routines
/workflows查看、暂停、恢复 workflow 的运行进度
/deep-research <question>内置 workflow:并行搜索、交叉核对来源,生成带引用的报告

跨设备与云端 ​

命令作用
/remote-control让本会话可以从 claude.ai 远程继续。别名 /rc
/teleport把云端会话拉到本地终端。别名 /tp
/desktop在桌面 App 里继续当前会话。别名 /app
/remote-env选择云端会话的默认环境
/web-setup用本地 gh 凭据为云端会话连接 GitHub
/mobile显示下载手机 App 的二维码。别名 /ios、/android

账号、用量与诊断 ​

命令作用
/login / /logout登录 / 登出 Anthropic 账号
/status版本、模型、账号、连接状态
/usage ★本次花费、套餐用量、活动统计。别名 /cost、/stats
/rate-limit-options撞到用量上限时的选项:等待自动继续、加购额度或升级
/usage-credits配置用量额度(原 /extra-usage)
/upgrade打开升级套餐页面
/privacy-settings隐私设置(Pro、Max)
/insights生成一份分析你近期使用习惯的 HTML 报告
/doctor(skill) 诊断安装、设置、扩展和 CLAUDE.md 问题,确认后帮你修;/doctor prompt-audit 审查指令文件里过时或冲突的内容。别名 /checkup
/debug [description](skill) 开启调试日志并帮你分析
/heapdump导出内存快照排查内存问题(菜单里隐藏,要打全名)
/bug [report]报 bug,发送前会让你确认附带多少会话内容。别名 /share
/feedback [report]发产品反馈
/release-notes查看更新日志
/help ★帮助和命令列表

集成与其他 ​

命令作用
/ide管理 IDE 集成
/chromeClaude in Chrome 设置
/claude-in-chrome [task](skill) 让 Claude 在浏览器里执行任务
/install-github-app为仓库安装 Claude GitHub App,可选配置 GitHub Actions
/install-slack-app安装 Claude Slack App
/claude-api [subcommand](skill) 加载 Claude API / Managed Agents 参考资料
/voice [hold|tap|off]语音输入
/team-onboarding根据你过去 30 天的使用记录生成团队上手指南
/powerup交互式小课程,带动画演示,用来发现功能
/artifacts、/design、/slides、/dataviz 等发布网页 Artifact、画设计稿、做幻灯片、图表设计指引(需要账号支持 Artifacts)
/setup-bedrock / /setup-vertex配置第三方云平台(设置对应环境变量后才出现)
/passes、/stickers、/radio送朋友试用、订贴纸、开 lo-fi 电台

已移除的命令:/vim(用 /config)、/pr-comments(直接让 Claude 去看 PR 评论)、/ultraplan(用计划模式)。

权限模式 ​

Shift+Tab 循环切换,状态栏会显示当前模式。

模式不问就能做的事适合
default(界面上叫 Manual)只有读取每一步都要自己过目
acceptEdits读取、改文件、常见文件系统命令(mkdir、mv、cp 等)边看边迭代
plan只读探索,不改源码,写出计划等你批准动手前先摸清代码库
auto全部,但有一个独立的分类器模型在后台审查每个动作长任务、不想被频繁打断
dontAsk工作目录内的读取和预先放行的工具,其他一律拒绝CI 和脚本
bypassPermissions全部只在隔离的容器 / 虚拟机里用

要点:

  • v2.1.283 起,交互式终端会话默认就从 auto 模式启动。claude -p 在没有任何设置指定模式时以 Manual 模式启动(v2.1.302 起)。
  • 循环顺序是 default → acceptEdits → plan,之后是可选的 bypassPermissions 和 auto。dontAsk 不在循环里,只能用 --permission-mode dontAsk 指定。
  • 计划写好后可以选:批准并进入 auto 模式、批准但每次编辑手动确认、或者继续改计划。批准前按 Ctrl+G 能在编辑器里直接改计划。
  • deny 规则在所有模式下都生效,包括 bypassPermissions。

权限规则 ​

规则写在 settings.json 的 permissions 里,格式是 Tool 或 Tool(specifier):

json
{
  "permissions": {
    "allow": ["Bash(npm run *)", "Bash(git commit *)"],
    "deny": ["Bash(git push *)", "Read(./.env)", "Read(./secrets/**)"]
  }
}
  • 判定顺序是 deny → ask → allow,先命中谁算谁,跟具体程度无关。所以宽泛的 deny 会压过精确的 allow。
  • * 要放在子命令后面:Bash(git log *) 只放行 git log,Bash(git *) 放行所有 git 命令。Bash(ls *) 不匹配 lsof(星号前的空格是规则的一部分),Bash(ls*) 则会匹配。
  • 只写工具名的 deny(如 Bash)会把整个工具从 Claude 的视野里拿掉。
  • .claudeignore 没有任何作用,要屏蔽文件请写 Read 的 deny 规则。
  • Read / Edit 规则只管 Claude 的文件工具和它能识别的 cat、head 之类命令,挡不住一个自己去读文件的 Python 脚本。要系统级隔离得开沙箱(/sandbox)。
  • 权限提示里选「Yes, and don't ask again」时,Bash 命令和域名规则会存进仓库根目录的 .claude/settings.local.json;文件修改的放行只到本次会话结束。

设置文件的优先级 ​

从高到低:组织下发的 managed 设置 → 命令行 --settings → .claude/settings.local.json(个人、本项目)→ .claude/settings.json(团队共享,提交到 git)→ ~/.claude/settings.json(个人、所有项目)。像 permissions.allow 这种列表会在各层之间合并,而不是互相覆盖。

记忆:CLAUDE.md 与自动记忆 ​

每个会话都从空白上下文开始,跨会话靠两样东西:你写的 CLAUDE.md,和 Claude 自己记的自动记忆。两者都只是放进上下文的文字,Claude 不保证照做;真要拦住某个动作,得用 hook 或权限规则。

CLAUDE.md 放在哪 ​

范围位置谁能看到
组织macOS 是 /Library/Application Support/ClaudeCode/CLAUDE.md全组织
用户~/.claude/CLAUDE.md你自己,所有项目
项目./CLAUDE.md 或 ./.claude/CLAUDE.md团队,提交到 git
本地./CLAUDE.local.md你自己,本项目,记得加进 .gitignore
  • 启动时会加载当前目录及所有上级目录的 CLAUDE.md,全部拼接起来而不是互相覆盖,越靠近工作目录的越后读到。子目录里的 CLAUDE.md 要等 Claude 读写那个子目录下的文件时才加载。
  • 用 @path/to/file 可以导入其他文件,比如 参见 @README 和 @package.json,最多递归四层。写在反引号里的 @README 不会被导入。
  • 块级 HTML 注释 <!-- ... --> 会在注入前被剥掉,适合给人看的备注。
  • 跑 /context 能在 Memory files 下确认哪些文件加载了。
  • 如果仓库只有 AGENTS.md,Claude Code 也能读它。

什么该写进 CLAUDE.md ​

官方的判断标准:同样的错误 Claude 犯第二次时;code review 抓到 Claude 本该知道的事时;你发现自己在重复上次会话说过的纠正时。只写每个会话都该知道的事实,比如构建命令、约定、目录结构。多步骤流程或只对某块代码有用的内容,改成 skill 或者按路径生效的规则。

太长的 CLAUDE.md 会被「看漏」。官方建议狠狠删:Claude 不写也能做对的,就删掉,或者改成 hook。

按路径生效的规则 ​

在 .claude/rules/ 下放 markdown 文件,加上 paths 就只在 Claude 碰到匹配文件时才加载:

md
---
paths:
  - "src/api/**/*.ts"
---

# API 开发规则

- 所有接口都要做输入校验

没有 paths 的规则在启动时就加载,优先级和 .claude/CLAUDE.md 相同。

自动记忆 ​

Claude 会根据你的纠正和偏好自己记笔记,存在 ~/.claude/projects/<project>/memory/,同一个 git 仓库的所有 worktree 共享一份。MEMORY.md 是索引,每次会话加载前 200 行或 25KB;具体条目放在单独的文件里,用到时才读。看到「Saved 2 memories」就是它在写。用 /memory 查看和开关,或者设 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 关闭。只存在本机,不跨机器同步。

检查点与回退 ​

每条开启新一轮的消息都会自动建一个检查点。按两下 Esc(输入框为空时)或 /rewind 打开回退菜单,选一条历史消息后可以:

  • Restore code and conversation:代码和对话都回到那时
  • Restore conversation:只回退对话,代码保留现状
  • Restore code:只回退代码,对话保留
  • Summarize from here / up to here:把那之后 / 之前的对话压成摘要,相当于定向的 /compact

检查点随对话保存,关掉终端、之后 /resume 回来还能回退。所以可以大胆让 Claude 尝试有风险的方案,不行就退回去。

局限要记住:

  • 只有 Bash 改过的文件不受追踪(rm、mv 之类的副作用退不回来)。
  • 子代理的编辑通常不会被恢复。
  • 你在外面手动改的、其他会话改的,也不追踪。
  • 符号链接和硬链接文件会被跳过,pnpm 硬链接进来的文件就属于这种。
  • 检查点只管会话内的快速恢复,长期的版本历史还是靠 git。

Skills:自定义命令 ​

Skill 就是一个带 frontmatter 的 SKILL.md。旧的 .claude/commands/xxx.md 仍然有效,和 .claude/skills/xxx/SKILL.md 一样都会生成 /xxx 命令,但新写的推荐用 skill(可以带附属文件)。

位置路径生效范围
个人~/.claude/skills/<name>/SKILL.md本机所有项目
项目.claude/skills/<name>/SKILL.md本仓库,提交后团队共享
插件<plugin>/skills/<name>/SKILL.md启用插件处,以 /plugin-name:skill-name 调用

一个最小例子:

md
---
name: fix-issue
description: 按编号修复 GitHub issue
disable-model-invocation: true
---

按我们的编码规范修复 GitHub issue $ARGUMENTS。

1. 读 issue 描述
2. 实现修复
3. 写测试
4. 提交

运行 /fix-issue 123,$ARGUMENTS 会替换成 123。

常用 frontmatter 字段:

字段作用
description做什么、何时用。Claude 靠它判断要不要自动调用,所以把关键用途写在前面
disable-model-invocationtrue 时 Claude 不会自己调用,只能你手动 /name
user-invocablefalse 时从 / 菜单隐藏,只给 Claude 用
allowed-tools本轮调用期间无需确认就能用的工具
argument-hint补全时提示参数,如 [issue-number]
model / effort这个 skill 运行时用的模型 / 推理强度
context: fork在一个分叉出来的子代理里运行,配合 agent 指定子代理类型
paths只在处理匹配文件时自动加载

参数和变量:$ARGUMENTS 是全部参数,$0、$1(即 $ARGUMENTS[0])按位置取,${CLAUDE_SKILL_DIR} 是 skill 所在目录,${CLAUDE_SESSION_ID} 是会话 ID。

在 skill 里写 !`gh pr diff` 这样的语法,命令会在发给 Claude 之前先执行,输出替换进内容里,Claude 拿到的是真实数据。

在 skill 内容或提示词里写 ultrathink,会让那一轮做更深的推理。注意 think、think hard 这些早期流传的说法现在只是普通文字,不是关键词。

改了 skill 文件可以 /reload-skills,不用重启。

子代理(Subagents) ​

子代理在独立的上下文窗口里工作,只把结论带回来,适合「读一大堆文件但只要结论」的活。内置的有:

  • Explore:只读,快速搜索和分析代码库,不加载 CLAUDE.md。
  • Plan:计划模式下用来调研的只读代理。
  • general-purpose:通用代理。

自定义子代理是一个 markdown 文件,放在 .claude/agents/(项目)或 ~/.claude/agents/(个人):

md
---
name: code-reviewer
description: 审查代码质量和最佳实践
tools: Read, Glob, Grep
model: sonnet
---

你是代码审查员。被调用时分析代码,给出关于质量、安全和最佳实践的具体建议。

正文就是它的系统提示。只有 name 和 description 是必填,其他常用字段:tools / disallowedTools、model、permissionMode、maxTurns、skills(预加载 skill)、memory(给它开持久记忆)、isolation: worktree(在临时 worktree 里干活,没改动就自动清理)。

调用方式,从弱到强:

  1. 自然语言:「用 code-reviewer 子代理看看我最近的改动」,由 Claude 决定是否委派。
  2. @ 提及:输入 @ 从补全里选,或手写 @agent-code-reviewer,保证一定用它。
  3. 整个会话都以它运行:claude --agent code-reviewer,或在 .claude/settings.json 里设 "agent": "code-reviewer"。

不用改配置也能用:直接说「用子代理调查一下认证系统怎么刷新 token」,调研就不会占你主对话的上下文。

Hooks:确定性的自动化 ​

CLAUDE.md 里写的是「建议」,Claude 可能不照做;hook 是 Claude Code 在特定时机一定会执行的命令。配置在 settings.json 的 hooks 下,分三层:事件 → matcher → 处理器。

官方的例子:拦截 rm -rf。

json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh",
            "args": []
          }
        ]
      }
    ]
  }
}
bash
#!/bin/bash
# .claude/hooks/block-rm.sh
COMMAND=$(jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q 'rm -rf'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Destructive command blocked by hook"
    }
  }'
else
  exit 0
fi

hook 从 stdin 读到一段 JSON(工具名、参数等)。退出码的含义:0 成功,打印的 JSON 字段生效;2 是阻断性错误,在能阻断的事件上会拦下动作,stderr 作为原因;其他非零值是非阻断错误,动作照常进行。

常用事件:

事件触发时机
SessionStart / SessionEnd会话开始(含恢复)/ 结束
UserPromptSubmit提交消息后、Claude 处理之前
PreToolUse工具调用之前,可以阻断
PostToolUse / PostToolUseFailure工具调用成功 / 失败之后,常用来自动格式化、跑 lint
PermissionRequest需要权限决定时
NotificationClaude Code 发通知时(比如等你确认),可以接系统通知
StopClaude 回复结束时,可以用来「测试不过不许停」
SubagentStart / SubagentStop子代理启动 / 结束
PreCompact / PostCompact上下文压缩前后

完整列表还有 InstructionsLoaded、CwdChanged、FileChanged、WorktreeCreate、PreModelSwitch 等,一共三十多个,见 官方 hooks 文档。除了 command,处理器还可以是 HTTP 请求、MCP 工具、一段提示词或一个代理。用 /hooks 查看当前配置,不想手写可以用 /update-config,比如「每次改完文件都跑 prettier」。

MCP:接入外部工具 ​

bash
# 远程 HTTP 服务器(推荐)
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 本地 stdio 服务器,-- 之后是启动命令
claude mcp add --env API_KEY=xxx --transport stdio myserver -- npx -y @example/mcp-server

# 直接给 JSON
claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

claude mcp list          # 列出所有服务器及连接状态
claude mcp get notion    # 查看详情
claude mcp remove notion # 删除

作用范围用 --scope(-s)指定:

范围生效共享存在
local(默认)仅当前项目否~/.claude.json
project仅当前项目是,提交到 git项目根目录的 .mcp.json
user所有项目否~/.claude.json

会话里用 /mcp 看状态、做 OAuth 登录。MCP 服务器提供的 prompt 会变成斜杠命令,资源可以用 @server:resource 引用。

非交互模式:放进脚本和 CI ​

bash
# 管道
cat build-error.txt | claude -p '简要解释这个构建错误的根因' > output.txt

# JSON 输出,用 jq 取结果
claude -p "总结这个项目" --output-format json | jq -r '.result'

# 预先放行工具
claude -p "跑测试并修复失败" --allowedTools "Bash,Read,Edit"

# 接着上一次对话
claude -p "现在重点看数据库查询" --continue

# 按会话 ID 续上
session_id=$(claude -p "开始评审" --output-format json | jq -r '.session_id')
claude -p "继续那次评审" --resume "$session_id"
  • -p 模式下需要审批的工具调用默认会被拒绝,所以要么 --allowedTools 预先放行,要么指定 --permission-mode(如 acceptEdits)。
  • 想要稳定的结构化结果,用 --json-schema;想实时流式处理,用 --output-format stream-json --verbose。
  • 加 --bare 可以跳过 hooks、插件、CLAUDE.md 等的自动发现,启动更快,结果也不受本机配置影响。
  • -p 会跳过工作区信任对话框,只在你信任的目录里用。

技巧清单 ​

这些来自官方的 最佳实践 文档,加上我自己用下来的体会。

给 Claude 一个能自己跑的检查 ​

我觉得这是最有用的一条。测试、构建退出码、lint、截图对比,任何能给出通过 / 不通过的东西都行。有了它,Claude 能自己反复改到通过;没有它,每个错误都要等你去发现。让它贴出证据:测试输出、跑了什么命令、返回了什么。想管得更严,可以用 /goal 设目标,或者用 Stop hook 在检查不过时不让它结束。

先探索,再计划,再写代码 ​

大改动前 Shift+Tab 切到计划模式或 /plan,让它先读代码、出方案,你审过再动手,免得解决了错误的问题。

管好上下文 ​

上下文窗口是最根本的限制,塞得越满,效果越差。

  • 不相关的任务之间 /clear。
  • /compact 重点保留 X 定向压缩;在 CLAUDE.md 里也可以写「压缩时始终保留改动过的文件列表和测试命令」。
  • 只想确认个细节,用 /btw,问答不进历史。
  • 调研交给子代理,结论回来,过程不占主上下文。
  • /context 看看是谁占了地方。

及早纠偏 ​

看到方向不对就按 Esc 打断,已做的工作不会丢。纠正两次还不对,就 /clear,把学到的东西写进一条更好的初始提示重新来,别在被失败尝试污染的上下文里死磕。

失败了就回退 ​

有检查点兜底,风险高一点的方案也可以让 Claude 先试,失败了 Esc Esc 退回去。Bash 命令造成的改动退不回来,这点要记着。

并行 ​

claude -w name 开独立的 worktree 同时跑几个会话;/fork 复制一份到后台;/batch 把大规模迁移拆给一群子代理。

零碎的小技巧 ​

  • 写长提示词按 Ctrl+G 在编辑器里写。
  • 打到一半想先问别的,Ctrl+S 暂存,问完再按一次取回。
  • Ctrl+C 误清了草稿,按 Up 找回来。
  • 命令跑得太久,Ctrl+B 丢到后台继续聊。
  • 可以让 Claude 先采访你:「在动手之前,先就这个需求问我问题」。
  • 新仓库第一次用:/init 生成 CLAUDE.md → /memory 补充 → /permissions 配好常用命令的放行,或者 /fewer-permission-prompts 自动生成。
  • 提交前:/diff 看改动,/code-review 找 bug,/simplify 清理,/security-review 查安全问题。
  • 常见的失败模式:一个会话里什么都干(「厨房水槽」式会话);CLAUDE.md 写得过长;不给验证手段就信任输出;不设范围地「调查一下」,结果读了几百个文件。

参考 ​

最后更新: